<TeXmacs|1.99.16>

<project|rehash.tm>

<style|tmmanual>

<\body>
  This is defined in <scm|(rehash fs progress-info)>. The procedure names of
  the original guile-gnunet bindings are preserved. Some undocumented
  bindings are exported as well.

  <\explain>
    <scm|(progress-info? <scm-arg|pinfo>)><explain-synopsis|Test if object is
    a progress info structure>
  </explain|Return <scm|#t> if <var|pinfo> is a progress information
  structure, <scm|#f> otherwise.>

  <\explain>
    <scm|(classify-progress-info <scm-arg|pinfo>)>
  <|explain>
    For a progress info structure, this will return two values, as two
    keywords. Possible first values:

    <\description>
      <item*|<scm|#:download>>for updates on downloads

      <item*|<scm|#:publish>><todo|todo>

      <item*|<todo|todo>><todo|todo>
    </description>

    Possible combinations:

    <\description>
      <item*|<scm|#:download #:progress>>for progress updates on downloads of
      regular files

      <item*|<scm|#:download #:error>>in case of some download error

      <item*|<scm|#:download #:start>><todo|todo>

      <item*|<scm|#:download #:resume>><todo|todo>

      <item*|<scm|#:download #:suspend>><todo|todo>

      <item*|<scm|#:download #:stopped>><todo|todo>

      <item*|<scm|#:download #:completed>><todo|todo>

      <item*|<scm|#:download #:lost-parent>><todo|todo>

      <item*|<todo|todo>><todo|todo>
    </description>
  </explain>

  <subsection|Interaction with C API>

  <\explain>
    <scm|(<scm|parse-c-progress-info> <scm-arg|pointer>)><explain-synopsis|Parse
    a C progress info structure>
  <|explain>
    Parse a <cpp|struct GNUNET_FS_ProgressInfo *>, into an equivalent Scheme
    <scm|progress-info?>. If \ <scm-arg|pointer> has a reference to a
    potentially large \<#2018\>data block\<#2019\> (currently, this only
    includes <scm|pinfo-download-bytevector>), it may be included in the
    Scheme object, so perhaps call <scm|progress-info-forget-c> before the
    data blocks are freed.
  </explain>

  <\explain>
    <scm|(progress-info-forget-c! <scm-arg|pinfo>)><explain-synopsis|Remove
    references to C structures>
  </explain|Remove references to C structures from <scm-arg|pinfo>. This may
  be useful to prevent accidentally use of a dangling pointer, as the C
  implementation doesn't use a garbage collector, instead it uses
  <cpp|malloc> and <cpp|free>.>

  <subsection|Download>

  <paragraph|Type predicates>

  <\explain>
    <scm|(pinfo-download? <scm-arg|pinfo>)><explain-synopsis|Test if object
    is a progress info structure for \ a download>
  </explain|Is <var|pinfo> an update on a download? This does not necessarily
  indicate progress! (An error is also possible.)>

  <\explain>
    <scm|(pinfo-download/progress? <scm-arg|pinfo>)><explain-synopsis|Test if
    object is a progress info for progress>
  </explain|Is <var|pinfo> an progress update on a download?>

  <\explain>
    <scm|(pinfo-download/error? <scm-arg|pinfo>)><explain-synopsis|Test if
    object is a progress info for an error>
  </explain|Is <var|pinfo> an progress info structure for an error when
  downloading?>

  <paragraph|Common properties>

  <\explain>
    <scm|(pinfo-download-eta <scm-arg|pinfo>)><explain-synopsis|Test if
    object is a progress info on a download>
  </explain|When is the download expected to be finished? Returned as an
  exact integer of microseconds (relative). This will be in the past for
  completed downloads.>

  <\explain>
    <scm|(pinfo-download-duration <scm-arg|pinfo>)><explain-synopsis|Current
    duration of download>
  </explain|How long was this download active? Returned as an exact integer
  of microsecods (relative)>

  <\explain>
    <scm|(pinfo-download-completed <scm-arg|pinfo>)>
  </explain|How many bytes were downloaded already? (Exact natural number,
  due to implementation limits <math|\<nosymbol\>\<less\>2<rsup|64>>)>

  <\explain>
    <scm|(pinfo-download-size <scm-arg|pinfo>)>
  </explain|Overall size of the download. For partial downloads, this will be
  smaller than the size in the URI.>

  <\explain>
    <scm|(pinfo-download-anonymity <scm-arg|pinfo>)><explain-synopsis|Anonymity
    level of download>
  </explain|level of anonymity (exact integer in range
  <math|<around*|[|0,2<rsup|32>-1|]>>) that was requested>

  <\explain>
    <scm|(pinfo-download-active? <scm-arg|pinfo>)>
  </explain|Whether the download is currently active.>

  <\explain>
    <scm|(pinfo-download-filename <scm-arg|pinfo>)>
  </explain|<todo|TODO>>

  <\explain>
    <scm|(pinfo-download-uri <scm-arg|pinfo>)>
  </explain|The URI for this download>

  <paragraph|Progress messages>Progress messages are sent when a part has
  been downloaded. If no filename is specified when starting the download,
  this will include the downloaded part itself. As the underlying C API
  exposes the block as a pointer (which will be freed), this would have to be
  copied to a bytevector for memory safety.

  As this can be somewhat expensive (but might be acceptable in practice),
  and not all callbacks require this data, this data isn't copied by default.
  Instead, this bytevector will be created on-demand (which may fail with a
  <scm|&data-out-of-scope> exception).

  <\explain>
    <scm|(call-with-data-pointer <scm-arg|pinfo>
    <scm|proc>)><explain-synopsis|Data pointer of progress message>
  <|explain>
    If <scm-arg|pinfo> still has a data pointer set, call <var|proc> with the
    data pointer. Otherwise, if pinfo has a bytevector set, call <var|proc>
    with the bytevector copy. Otherwise, if <var|pinfo> had some data at some
    point (but it hasn't been copied), call <var|proc> with <scm|#t>.
    Otherwise, <var|pinfo> never had a data block, and <var|proc> is called
    without any arguments.

    As an (imperfect, as <var|proc> could stash the pointer somewhere, and
    cross-thread continuation madness<\footnote>
      Hypothetical situation: (1) lose common sense, (2) establish a prompt,
      call <scm|call-with-data-pointer> and abort to the prompt from
      <var|proc>, in a context where the pointer is still valid, (3) invoke
      the delimited continuation from thread #A and reset the pointer from
      thread #B. (4) Watch the fireworks! Maybe this race can be resolved by
      grabbing & releases mutexes at the right locations, but that's going a
      bit far. <todo|maybe actually do this! Sounds fun actually.>
    </footnote>) memory safety measure, a
    \<#2018\><scm|dynamic-wind>\<#2019\> is established, that will raise a
    <scm|&data-out-of-scope> exception if <var|proc> is re-entered when the
    data pointer has disappeared. This is merely a (perhaps very convenient
    and reliable) debugging aid, don't rely on this!
  </explain>

  <\explain>
    <scm|(pinfo-download-bytevector <scm-arg|pinfo>)><explain-synopsis|Bytevector
    of progress message>
  <|explain>
    If <var|pinfo> never any data, return <scm|#f>. If <var|pinfo> had some
    data at some point, but it has been forgotten, return <scm|#t>.
    Otherwise, return a (cached) bytevector copy of the data.
  </explain>

  <\explain>
    <scm|(pinfo-download-offset <scm-arg|pinfo>)><explain-synopsis|Offset of
    data block>
  </explain|Offset (in bytes) into the file of the downloaded block.>

  <\explain>
    <scm|(pinfo-download-data-length <scm-arg|pinfo>)><explain-synopsis|Offset
    of data block>
  </explain|Length (in bytes) into the file of the downloaded block.>

  <paragraph|Download error messages><todo|todo when is an error message
  possible>

  <scm|(pinfo-download-error-message <scm-arg|pinfo>)>

  <paragraph|Download start><todo|todo>

  <paragraph|Download resume><todo|todo>

  <subsection|Publishing>

  <todo|todo>

  <subsection|Searching>

  <todo|todo>

  <subsection|Exceptions>

  <\explain>
    <scm|&data-out-of-scope>, <scm|data-out-of-scope?>,
    <scm|make-data-out-of-scope>
  </explain|See <scm|call-with-data-pointer>.>
</body>

<\initial>
  <\collection>
    <associate|save-aux|false>
  </collection>
</initial>